From: Marco Trevisan (Treviño) <mail@3v1n0.net>
Date: Tue, 28 May 2019 06:30:10 +0000 (+0200)
Subject: docs: Update `actor` and `delegate_` paragraph in HACKING
X-Git-Tag: archive/raspbian/50.5-1+rpi1~1^2~781^2^2~518
X-Git-Url: https://dgit.raspbian.org/%22http://www.example.com/cgi/%22/%22http:/www.example.com/cgi/%22?a=commitdiff_plain;h=c9fbae3408ba444f2d63add6a4c90b1bb6c2ad53;p=gnome-shell.git

docs: Update `actor` and `delegate_` paragraph in HACKING

Deprecate the usage of the `actor` property, while keep the `_delegate` part
as it is needed for DnD for now.

https://gitlab.gnome.org/GNOME/gnome-shell/merge_requests/559
---

diff --git a/HACKING.md b/HACKING.md
index 3e2450b18..05176c45f 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -186,15 +186,27 @@ and "double quotes" for strings that the user may see. This allows us to
 quickly find untranslated or mistranslated strings by grepping through the
 sources for double quotes without a gettext call around them.
 
-## `actor` and `_delegate`
+## `actor` (deprecated) and `_delegate`
 
 gjs allows us to set so-called "expando properties" on introspected objects,
 allowing us to treat them like any other. Because the Shell was built before
-you could inherit from GTypes natively in JS, we usually have a wrapper class
-that has a property called `actor`. We call this wrapper class the "delegate".
+you could inherit from GTypes natively in JS, in some cases we have a wrapper
+class that has a property called `actor` (now deprecated). We call this
+wrapper class the "delegate".
 
 We sometimes use expando properties to set a property called `_delegate` on
 the actor itself:
+```javascript
+    var MyActor = GObject.registerClass(
+    class MyActor extends Clutter.Actor {
+        _init(params) {
+            super._init(params);
+            this._delegate = this;
+        }
+    });
+```
+
+Or using the deprecated `actor`:
 ```javascript
     var MyClass = class {
         constructor() {
@@ -215,6 +227,7 @@ delegate object from an associated actor. For instance, the drag and drop
 system calls the `handleDragOver` function on the delegate of a "drop target"
 when the user drags an item over it. If you do not set the `_delegate`
 property, your actor will not be able to be dropped onto.
+In case the class is an actor itself, the `_delegate` can be just set to `this`.
 
 ## Functional style